
Documentation for XprMod v1.10 
(Tab width 8)


XprMod by Skoe of Expression
Thanks to MikMak for many sources!


================================================================
Introduction
================================================================

XprMod is a multitrack, multiformat (multimedia, hehe) sound
module player. It can play up to 32 channels with real panning
(stereo) effects and on fast processors with interpolation.

This version can load various PC, Amiga and Atari MOD files,
XM, S3M and MTM. Other formats will be added in future versions.

Several SWIs can be used to control the player, see below. You
can (and shall) use the auto-setup option to get the best
quality on fast processors (ARM7, SA110) and the highest speed
on slow ones (ARM 3).

XprMod runs also on cacheless processors, but they are history
and so nothing is optimised for these ones. I could make the 
player about 30% faster on ARM2, but it's a senseless waste of
time.

Don't use it for tracks with 8 voices or less - convert them!
Players like DigitalSymphony or MatrixTrack8 (using the 8 
physical channels of the Acorn sound system) are much faster
with these tracks than XprMod, because it uses always software
mixing. Perhaps I will implement 2 different routines later...


================================================================
Copyright
================================================================

XprMod is based on MikMaks MikMod. It is no simple port but
was totally revised and partly re-written. Future releases will
have only less in common with MikMod, because even the internal
structure of this player and most routines will be changed.

You may (and must :) use XprMod (unchanged) in your products. 
Please credit me with something like "Music player by Skoe of 
Expression". If you use it in a commercial product of any kind
(CD-ROM's, Games etc.) and you'll sell more than 20 copies of
it, you must (!) give me 20 pounds or a free copy of this
product. If you don't do that, it is a violation of the copy-
right laws!

If you include the player module as a single file into your
application, please copy this file into it, too. You needn't do
this if you have real problems with space (e.g. a 1599 kB demo).

The author of this player will not be responsible for any
loss or damage caused by this software.


My addy:

Thomas Giesel
Hauptstr. 61
D-03246 Crinitz
Germany


================================================================
Speed
================================================================

It is possible to play

- up to about 10 channels on ARM2 with 14kHz (in a bad quality)
  (but who cares about 8Mhz machines?!)
  -> use DSym or similar programs !!!
- up to about 24 channels on ARM3
- up to 32 channels with 41kHz mixing and interpolation
  on SA110 (needs 20% processor (or better: RAM) speed or less)

Following tests were made by Mr. Hill of Icebird (thanx!) with an
older XprMod v0.30:

SA110, 60ns RAM (RPC 600 board): 41kHz, real stereo, interpolated

              XprMod  QuantumPlayer(24µs)  MatrixPlayer(24µs)
    4 channel  6.38%        5.42%             -not tested-
    8 channel  8.47%      -gave up-           -not tested-
   11 channel 12.24%      -gave up-              23.54%
   16 channel 16.41%      -gave up-              24.91%
   20 channel 14.30%      -gave up-           -not tested-
   30 channel 21.71%      -gave up-           -not tested-


The player needs about half of the speed without interpolation 
and real stereo mixing (depending on hardware configuration).


================================================================
Mixing Quality
================================================================

If you use the auto-setup option, you can be sure that the
player will find a good compromise between quality and speed on
nearly every machine.

You may choose following modes:

high quality:
 use a high sampling frequency, real stereo (all panning
 effects) and interpolate if possible

normal quality:
 use a medium frequency and real stereo

fast mode:
 use a low quality (max. 22kHz) and fast stereo mode (mix to two
 fix stereo positions, panning disabled)

If the computer system to slow or to fast :) you could get also
15kHz with fast stereo mode when chosen "high quality" or
real stereo in "fast mode".

I offer you to use "high quality" in desktop players and music-
compilations, "normal quality" in demos and "fast mode" only if
you or your computer is ill. Or simple include a button...




================================================================
Fast Guide
================================================================

SYS"ExpressionMod_Load", "ADFS::4.$.XMFile", 0, -2
REM 0 -> file, -2 -> normal quality
SYS"ExpressionMod_Play", 1
REM 1 -> restart after end

Enough for a first test?!

- Don't forget to stop your track before exit your program
- Don't start other players while XprMod is playing! To get
  a higher speed XprMod and most other players are not 100%
  Acorn conform and could crash or play strange sounds.


================================================================
Software Interrupts
================================================================

temporary SWI chunk base number 0x8A800, NOT allocated by Acorn
              - Use it on your own risk !!! -

Note:	"Returns error block" means: if an error is occurred,
	the SWI will return with V set and R0 pointing to a
	standard Risc OS error block. If the SWI X-bit is not
	set, the OS will report the error as usual.
	If nothing unpleasant happened the registers return
	like described.


================================================================
SWI ExpressionMod_Load		base + 0x00
================================================================

Use this SWI to load a file from a FS or RAM and to choose the
quality. If the file doesn't exist or cannot be loaded, an error
will be returned. Loading could take some seconds, because the 
track will be converted into an internal format. This is the
only chance to change the setup, after loading you can't do it.

Entry:
	R0	pointer to filename (or pointer to track in
		memory if R1 > 0)

	R1	0 to load from file, else length of track
		in memory

	R2	quality

		if minus: auto setup DEPENDING FROM SYSTEM SPEED
		for detailed notes see chapter "Mixing Quality"

			-1: try to use high quality
			    (interpolated, real stereo,
			    high mixing frequency)

			-2: normal
			    (real stereo, normal mixing
			    frequency)

			-3: fast, (avoid this mode!)
			    (left - right only, low freq)

		else: custom setup

			bit 0: interpolate samples
			bit 1: use real stereo mixing

	R3	mixing frequency only if custom setup
		14000 <= R2 <= 41000, other values will become
		clipped
	R4	0 !!! (for future extensions, not tested yet)

Exit:
	returns error block or
	all	preserved


================================================================
SWI ExpressionMod_Play		base + 0x01
================================================================

After loading or pausing you can (re)start playing with this
SWI. It is possible to repeat a song or to play it only once.
After playing once, ExpressionMod_Stop will be called
automatically. It is not impossible that an error occurres!

Entry:
	R0	= 0 for playing only once
		    anything else for repeating song
		    (ignored at restart after pausing)
	R1	= 0 (for future extensions)

Exit:
	returns error block or
	all	preserved


================================================================
SWI ExpressionMod_Pause		base + 0x02
================================================================

Does not detach the channels, only stops playing until
ExpressionMod_Play was called.

Entry:
	-

Exit:
	all	preserved



================================================================
SWI ExpressionMod_Stop		base + 0x03
================================================================

Stop playing and discard loaded song.

Entry:
	-

Exit:
	all	preserved



================================================================
SWI ExpressionMod_Position	base + 0x04
================================================================

You can set the song position (patter number) and/or read the
position and row number. This can be done before starting,
while playing or pause.

Entry:
	R0	= 0 to read
	or
	R0	position to set
	
Exit:
	R0	position (pattern number)
	R1	row
	rest	preserved


================================================================
SWI ExpressionMod_Info		base + 0x05
================================================================

Read various infos.

Entry:
	-

Exit:
	R0	pointer to songname
	R1	pointer to modtype
		e.g. "FastTracker v2.00"
	R2	number of logical channels
	R3	number of patterns
	R4	used mixing frequency in Hertz
	R5	mixing mode:
		bit 0 set if interpolated (else normal)
		bit 1 set if real stereo (else fast left/right)

================================================================
SWI ExpressionMod_Volume	base + 0x06
================================================================

Set volume 0 (silent) to 128. Forbidden values will be treated
as 128. No error returning necessary. This can be done always.

Normally the amplifier uses the right setting for a high volume
without distortion. Nevertheless it may happen that the player
overdrives and plays crackling sounds. In this case choose a 
lower volume.

Entry:
	R0	volume

Exit:
	all	preserved


================================================================
SWI ExpressionMod_Prev		base + 0x07
================================================================

Jump to previous pattern (if existing).

Entry:
	-
	
Exit:
	all	preserved


================================================================
SWI ExpressionMod_Next		base + 0x08
================================================================

Jump to next pattern (if existing).


Entry:
	-

Exit:
	all	preserved




EOF